Azure Maps Route Service (stable:2025-01-01)

2025/03/04 • 10 new methods

Route_PostRouteDirections (new)
Description :  The `Route Directions` API is an HTTP `POST` request that returns the ideal route between an origin and destination for automobile (driving), commercial trucks and walking routes. The route passes through a series of waypoints if specified. A waypoint is a geographical location defined by longitude and latitude that is used for navigational purposes. The route considers factors such as current traffic and the typical road speeds on the requested day of the week and time of day. The API returns the distance, estimated travel time, and a representation of the route geometry. More routing information such as an optimized waypoint order or turn by turn instructions is also available, depending on the parameters used. The Route Directions considers local laws, vehicle dimensions, cargo type, max speed, bridge and tunnel heights to calculate the truck specific routes and avoid complex maneuvers and difficult roads. Not all trucks can travel the same routes as other vehicles due to certain restrictions based on the vehicle profile or cargo type. For example, highways often have separate speed limits for trucks, some roads don't allow trucks with flammable or hazardous materials, and there can be height and weight restriction on bridges. Up to 25 waypoints and 10 viaWaypoints between any two waypoints is supported for driving and walking routes. Each set of waypoints creates a separate route Leg. ViaWaypoints define the route path and can be used for route creation through specific locations, but they don't create route Legs. Truck routes support up to 150 waypoints but don't support viaWaypoints. For information about routing availability in countries/regions, see [Azure Maps routing coverage](https://learn.microsoft.com/azure/azure-maps/routing-coverage?pivots=route-v2). >[!Important] >By using this feature, you agree to the preview legal terms. For more information, see [Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
Reference :  Link ¶

⚼ Request

POST:  /route/directions
{
api-version:
{
Description: Version number of Azure Maps API. ,
Required: True ,
}
string ,
x-ms-client-id:
{
Description: Specifies which account is intended for usage in conjunction with the Microsoft Entra ID security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Microsoft Entra ID security in Azure Maps see the following [articles](https://aka.ms/amauthdetails) for guidance. ,
Required: False ,
}
string ,
Accept-Language:
{
Description: Language in which routing results should be returned. For more information, see [Localization support in Azure Maps](https://learn.microsoft.com/azure/azure-maps/supported-languages#routing-v2-services-preview-supported-languages). ,
Required: False ,
}
string ,
routeDirectionsRequest:
{
Description: Request body of RouteDirections API in GeoJSON format. ,
Required: True ,
}
{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is `FeatureCollection`. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
FeatureCollection: Specifies the `GeoJSON` `FeatureCollection` object type. ,
}
,
Required: True ,
}
enum ,
features:
{
Description: Driving and walking routes are defined by a set of waypoints(stops) and viaWaypoints (intermediate locations that the route must pass through). You can have a maximum of 25 waypoints, and a maximum of 10 viaWaypoints between each set of waypoints. Truck route supports up to 150 waypoints and viaWaypoints are not supported. A route must have a minimum of 2 waypoints and the start and end points of the route cannot be viaWaypoints. Both waypoint and viaWaypoint locations must be specified as a valid GeoJSON Point feature object along with pointIndex that specifies the order of the locations. For more information on the GeoJSON format, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Required: True ,
}
[
{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is Feature. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
Feature: Specifies the `GeoJSON` Feature object type. ,
}
,
Required: True ,
}
enum ,
geometry:
{
Description: A valid `GeoJSON Point` geometry type. Please refer to [RFC 7946](https://tools.ietf.org/html/rfc7946#section-3.1.2) for details. ,
Required: True ,
}
object ,
properties:
{
Description: Specifies the properties of a Waypoint which is a specific location or point along a route or trip that serves as a reference or stopping point. ,
Required: True ,
}
{
pointIndex:
{
Description: Identify and order the sequence of waypoints in the route. The default value is the `index value` of a features array. ,
Format: int64 ,
Required: False ,
}
integer ,
pointType:
{
Description: Waypoint type on the route. It can be a stop or an intermediate location that the route must pass through. ,
Enum:
{
waypoint: A waypoint is a specific location or point along a route or trip that serves as a reference or stopping point. ,
viaWaypoint: A viaWaypoint is a specific waypoint that must be passed through or visited along a route or trip. `Note`: Only supported for driving travelMode. ,
}
,
Required: False ,
}
enum ,
}
,
}
,
]
,
travelMode:
{
Description: The mode of travel for the requested route. If not defined, the default value is "driving" that returns the route optimized for cars. `Note`: For truck travelMode, the requested truck route may not be available for the entire route. Where the truck route is not available for a particular section, the travelMode element of the response for that section will be "other". Example: "travelMode":"driving" ,
Enum:
{
driving: The returned routes are optimized for cars. ,
truck: The returned routes are optimized for large size trucks based on the vehicle specification. ,
walking: The returned routes are optimized for pedestrians, including the use of sidewalks. ,
}
,
Required: False ,
}
enum ,
departAt:
{
Description: The date and time of departure from the origin point formatted as a `dateTime` value defined by [RFC 3339, section 5.6](https://www.rfc-editor.org/rfc/rfc3339#section-5.6). When a time zone offset is not specified, UTC will be assumed. If the `departAt` is not set, the default value is the current time. Example: "departAt": "2023-06-01T09:30:00.000-07:00" ,
Format: date-time ,
Required: False ,
}
string ,
arriveAt:
{
Description: The date and time of arrival at the destination point formatted as a `dateTime` value defined by [RFC 3339, section 5.6](https://www.rfc-editor.org/rfc/rfc3339#section-5.6). When a time zone offset is not specified, UTC will be assumed. The `arriveAt` parameter cannot be used in conjunction with `departAt`. Example: "arriveAt": "2023-06-01T09:30:00.000-07:00" ,
Format: date-time ,
Required: False ,
}
string ,
optimizeRoute:
{
Description: Specifies the parameter to use to optimize the route. If not defined, the default is "fastestWithoutTraffic" which returns the route to minimize the travel time without using current traffic information. Example: "optimizeRoute":"shortest" ,
Enum:
{
shortest: The route is calculated to minimize the distance. Traffic information is not used. ,
fastestWithoutTraffic: Finds the fastest route, without factoring in traffic information. ,
fastestAvoidClosureWithoutTraffic: The route is calculated to minimize the time and avoid road closures. No traffic information except for road closures is used in the calculation. `Note`: Only supported for driving travelMode. ,
fastestWithTraffic: The route is calculated to minimize the time using current traffic information. `Note`: Only supported for driving and truck travelMode. ,
}
,
Required: False ,
}
enum ,
optimizeWaypointOrder:
{
Description: Re-order the route waypoints using a fast heuristic algorithm to reduce the route cost specified with the optimize parameter. The origin and destination are excluded from the optimized waypoint and their position is considered fixed. Acceptable values are true or false. `Note`: Only supported for truck travelMode. ,
Required: False ,
}
boolean ,
avoid:
{
Description: Specifies restrictions that the route calculation should honor when determining the route. Avoid supports multiple values in a request and is only supported for the driving and truck travelMode. Example: "avoid": ["limitedAccessHighways", "tollRoads"] ,
Required: False ,
}
[
string ,
]
,
routeOutputOptions:
{
Description: Include the desired route information from the response. By default, the itinerary is included in the response. Supports multiple values such as "routeOutputOptions": ["routePath", "regionTravelSummary"] ,
Required: False ,
}
[
string ,
]
,
maxRouteCount:
{
Description: The maximum number of routes to return. Available for the driving and truck travel modes. For driving routes, this parameter supports routes with up to two waypoints in addition to the origin and destination and avoid parameter must not be set. Default: "maxRouteCount":1 Minimum: "maxRouteCount":1 Maximum: "maxRouteCount":3 ,
Format: int64 ,
Required: False ,
}
integer ,
heading:
{
Description: The initial directional heading of the vehicle in degrees starting at true North and continuing in clockwise direction. North is 0 degrees, east is 90 degrees, south is 180 degrees, west is 270 degrees. Possible values 0-359 ,
Format: int64 ,
Required: False ,
}
integer ,
vehicleSpec:
{
Description: Specifies the vehicle attributes such as size, weight, max speed, type of cargo, etc. for truck routing only. This helps avoid low bridge clearances, road restrictions, difficult right turns to provide the optimized truck route based on the vehicle specifications. `Note`: Only supported for truck travelMode ,
Required: False ,
}
object ,
}
,
}

⚐ Response (200)

{
$schema:
{
Description: This object is returned from a successful call. ,
}
object ,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for Azure Maps APIs to return error details for failed operations. ,
}
{
error:
{
Description: The error detail. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Required: False ,
}
string ,
message:
{
Description: A human-readable representation of the error. ,
Required: False ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}
Route_PostRouteDirectionsBatch (new)
Description :  The `Route Directions Batch` API is an HTTP `POST` request that sends batches of up to **100** queries in a single call to the [Route Directions](/rest/api/maps/route/post-route-directions?view=rest-maps-2025-01-01) API. >[!Important] >By using this feature, you agree to the preview legal terms. See the [Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional details. ### Submit Synchronous Batch Request The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API. ``` POST https://atlas.microsoft.com/route/directions:batch?api-version=2025-01-01 ``` ### POST Body for Batch Request To send the _directions_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 2 _directions_ queries: ``` { "batchItems": [ { "optionalId": "bbc9c0f6-ab52-49d8-a788-a658fa654c94", "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "coordinates": [ -122.3368, 47.614988 ], "type": "Point" }, "properties": { "pointIndex": 0, "pointType": "waypoint" } }, { "type": "Feature", "geometry": { "coordinates": [ -122.316067, 47.606356 ], "type": "Point" }, "properties": { "pointIndex": 1, "pointType": "waypoint" } } ], "optimizeRoute": "fastestWithoutTraffic", "routeOutputOptions": [ "routeSummary" ], "maxRouteCount": 3, "travelMode": "driving" }, { "optionalId": "a191de3c-1268-4986-98f0-03f0a5d9302a", "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "coordinates": [ -122.3368, 47.614988 ], "type": "Point" }, "properties": { "pointIndex": 0, "pointType": "waypoint" } }, { "type": "Feature", "geometry": { "coordinates": [ -122.316067, 47.606356 ], "type": "Point" }, "properties": { "pointIndex": 1, "pointType": "waypoint" } } ], "optimizeRoute": "shortest", "routeOutputOptions": [ "routeSummary" ], "maxRouteCount": 2, "travelMode": "driving" } ] } ``` A _directions_ batchItem object can accept any of the supported _directions_ [Request body](/rest/api/maps/route/post-route-directions?view=rest-maps-2025-01-01#request-body) The batch should contain at least **1** query. ### Batch Response Model The batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types: - [`DirectionsResponse`](/rest/api/maps/route/post-directions#response) - If the query completed successfully. - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.
Reference :  Link ¶

⚼ Request

POST:  /route/directions:batch
{
x-ms-client-id:
{
Description: Specifies which account is intended for usage in conjunction with the Microsoft Entra ID security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Microsoft Entra ID security in Azure Maps see the following [articles](https://aka.ms/amauthdetails) for guidance. ,
Required: False ,
}
string ,
api-version:
{
Description: Version number of Azure Maps API. ,
Required: True ,
}
string ,
Accept-Language:
{
Description: Language in which routing results should be returned. For more information, see [Localization support in Azure Maps](https://learn.microsoft.com/azure/azure-maps/supported-languages#routing-v2-services-preview-supported-languages). ,
Required: False ,
}
string ,
routeDirectionsBatchRequest:
{
Description: The list of route directions queries/requests to process. The list can contain a max of 100 queries for sync version and must contain at least 1 query. ,
Required: True ,
}
{
batchItems:
{
Description: The list of queries to process. ,
Required: False ,
}
[
object ,
]
,
}
,
}

⚐ Response (200)

{
summary:
{
Description: Summary for the batch request ,
Required: False ,
}
{
successfulRequests:
{
Description: Number of successful requests in the batch ,
Format: int32 ,
Required: False ,
}
integer ,
totalRequests:
{
Description: Total number of requests in the batch ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
batchItems:
{
Description: Array containing the batch results. ,
Required: False ,
}
[
object ,
]
,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for Azure Maps APIs to return error details for failed operations. ,
}
{
error:
{
Description: The error detail. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Required: False ,
}
string ,
message:
{
Description: A human-readable representation of the error. ,
Required: False ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}
Route_PostSnapToRoads (new)
Description :  The Snap to Roads API accepts GPS point data, represented as longitude and latitude coordinates, and generates points that aligns with existing roadways on a map. This process, known as "snapping to roads", produces a series of objects that trace a path closely following the road network. The resulting data includes road names and their respective speed limits, pertinent to the traversed segments. Moreover, the Snap to Roads API offers an interpolation feature, which refines the GPS points to create a smoother route that adheres to the road's geometry. This functionality is especially beneficial for asset tracking and enhancing data visualization in mapping applications. >[!Important] > The GPS points must be within 2.5 kilometer of each other. For information about routing availability in countries/regions, see [Azure Maps routing coverage](https://learn.microsoft.com/azure/azure-maps/routing-coverage?pivots=route-v2). >[!Important] >By using this feature, you agree to the preview legal terms. See the [Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional details.
Reference :  Link ¶

⚼ Request

POST:  /route/snapToRoads
{
api-version:
{
Description: Version number of Azure Maps API. ,
Required: True ,
}
string ,
x-ms-client-id:
{
Description: Specifies which account is intended for usage in conjunction with the Microsoft Entra ID security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Microsoft Entra ID security in Azure Maps see the following [articles](https://aka.ms/amauthdetails) for guidance. ,
Required: False ,
}
string ,
Accept-Language:
{
Description: Language in which routing results should be returned. For more information, see [Localization support in Azure Maps](https://learn.microsoft.com/azure/azure-maps/supported-languages#routing-v2-services-preview-supported-languages). ,
Required: False ,
}
string ,
snapToRoadsRequest:
{
Description: Request body of SnapToRoads API in GeoJSON format. ,
Required: True ,
}
{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is `FeatureCollection`. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
FeatureCollection: Specifies the `GeoJSON` `FeatureCollection` object type. ,
}
,
Required: True ,
}
enum ,
features:
{
Description: A set of points to snap to road network. You can have a maximum of 100 points and the two consecutive points must be within 2.5 kilometer of each other. Refer to [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946) for details on the GeoJSON format. `Note`: The API will not return a point object in the response for the GPS point that cannot be snapped to a road network. ,
Required: True ,
}
[
{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is Feature. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
Feature: Specifies the `GeoJSON` Feature object type. ,
}
,
Required: True ,
}
enum ,
geometry:
{
Description: A valid `GeoJSON Point` geometry type. Please refer to [RFC 7946](https://tools.ietf.org/html/rfc7946#section-3.1.2) for details. ,
Required: True ,
}
object ,
properties:
{
Description: The properties object is required in a valid GeoJSON but it can be empty since the metadata is not used for snapping to road. ,
Required: True ,
}
object ,
}
,
]
,
interpolate:
{
Description: Specifies whether to return additional points between the snapped points to complete the full route path that smoothly follows the road geometry. The interpolated points will have `isInterpolate:true` in the response which can be used to identify the snapped points from interpolated points. ,
Required: False ,
}
boolean ,
includeSpeedLimit:
{
Description: Specifies whether to include speed limit information for the snapped points in the response. The unit is in kilometers per hour. `Note`: Only supported for driving travelMode. ,
Required: False ,
}
boolean ,
travelMode:
{
Description: Specifies the routing profile for snapping the points. If unspecified, the default mode is "driving", which optimizes the snapped points for driving routes. ,
Enum:
{
driving: The points are snapped to the road suitable for cars. ,
walking: The points are snapped to the pedestrian route including the use of sidewalks. ,
}
,
Required: False ,
}
enum ,
}
,
}

⚐ Response (200)

{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is `FeatureCollection`. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
FeatureCollection: Specifies the `GeoJSON` `FeatureCollection` object type. ,
}
,
Required: False ,
}
enum ,
features:
{
Description: `GeoJSON` feature object that contains Geometry object and additional properties. Refer to [RFC 7946, Section 3.2](https://www.rfc-editor.org/rfc/rfc7946#section-3.2) for details. ,
Required: False ,
}
[
object ,
]
,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for Azure Maps APIs to return error details for failed operations. ,
}
{
error:
{
Description: The error detail. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Required: False ,
}
string ,
message:
{
Description: A human-readable representation of the error. ,
Required: False ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}
Route_PostSnapToRoadsBatch (new)
Description :  The Snap To Roads Batch API sends batches of up to **100** queries as a single call to the [Snap To Roads API](/rest/api/maps/route/post-snap-to-roads?view=rest-maps-2025-01-01). >[!Important] >By using this feature, you agree to the preview legal terms. See the [Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional details. ### Submit Synchronous Batch Request The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API. ``` POST https://atlas.microsoft.com/route/snapToRoads:batch?api-version=2025-01-01 ``` ### POST Body for Batch Request To send the _snap to roads_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 2 _snap to roads_ queries: ``` { "batchItems": [ { "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "coordinates": [ -122.122353, 47.672662 ], "type": "Point" }, "properties": { } }, { "type": "Feature", "geometry": { "coordinates": [ -122.132452, 47.644234 ], "type": "Point" }, "properties": { } } ], "interpolate": true, "includeSpeedLimit": true, "travelMode": "driving" }, { "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "coordinates": [ -122.33669, 47.590849 ], "type": "Point" }, "properties": { "pointIndex": 0 } }, { "type": "Feature", "geometry": { "coordinates": [ 122.34509, 47.610524 ], "type": "Point" }, "properties": { "pointIndex": 1 } } ], "interpolate": false, "includeSpeedLimit": false, "travelMode": "driving" } ] } ``` A _snap to roads_ batchItem object can accept any of the supported _snap to roads_ [Request body](/rest/api/maps/route/post-snap-to-roads?view=rest-maps-2025-01-01#request-body) The batch should contain at least **1** query. ### Batch Response Model The batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types: - [`SnapToRoadsResponse`](/rest/api/maps/route/post-snap-to-roads#response) - If the query completed successfully. - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.
Reference :  Link ¶

⚼ Request

POST:  /route/snapToRoads:batch
{
x-ms-client-id:
{
Description: Specifies which account is intended for usage in conjunction with the Microsoft Entra ID security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Microsoft Entra ID security in Azure Maps see the following [articles](https://aka.ms/amauthdetails) for guidance. ,
Required: False ,
}
string ,
api-version:
{
Description: Version number of Azure Maps API. ,
Required: True ,
}
string ,
Accept-Language:
{
Description: Language in which routing results should be returned. For more information, see [Localization support in Azure Maps](https://learn.microsoft.com/azure/azure-maps/supported-languages#routing-v2-services-preview-supported-languages). ,
Required: False ,
}
string ,
snapToRoadsBatchRequest:
{
Description: The list of Snap To Roads queries/requests to process. The list can contain a max of 100 queries for sync version and must contain at least 1 query. ,
Required: True ,
}
{
batchItems:
{
Description: The list of queries to process. ,
Required: False ,
}
[
object ,
]
,
}
,
}

⚐ Response (200)

{
summary:
{
Description: Summary for the batch request ,
Required: False ,
}
{
successfulRequests:
{
Description: Number of successful requests in the batch ,
Format: int32 ,
Required: False ,
}
integer ,
totalRequests:
{
Description: Total number of requests in the batch ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
batchItems:
{
Description: Array containing the batch results. ,
Required: False ,
}
[
object ,
]
,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for Azure Maps APIs to return error details for failed operations. ,
}
{
error:
{
Description: The error detail. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Required: False ,
}
string ,
message:
{
Description: A human-readable representation of the error. ,
Required: False ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}
Route_PostRouteRange (new)
Description :  The Route Range API creates a polygon that depicts the area reachable from a given location within a certain threshold based on the specified time or distance budget. A polygon boundary (or Isochrone) is returned in a counterclockwise orientation as well as the precise polygon center which was the result of the origin point. The returned polygon can be used for spatial filtering to search for features of interest within the provided Isochrone. For information about routing availability in countries/regions, see [Azure Maps routing coverage](https://learn.microsoft.com/azure/azure-maps/routing-coverage?pivots=route-v2). >[!Important] >By using this feature, you agree to the preview legal terms. See the [Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional details.
Reference :  Link ¶

⚼ Request

POST:  /route/range
{
api-version:
{
Description: Version number of Azure Maps API. ,
Required: True ,
}
string ,
x-ms-client-id:
{
Description: Specifies which account is intended for usage in conjunction with the Microsoft Entra ID security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Microsoft Entra ID security in Azure Maps see the following [articles](https://aka.ms/amauthdetails) for guidance. ,
Required: False ,
}
string ,
routeRangeRequest:
{
Description: Request body of RouteRange API in GeoJSON format. ,
Required: True ,
}
{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is Feature. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
Feature: Specifies the `GeoJSON` Feature object type. ,
}
,
Required: True ,
}
enum ,
geometry:
{
Description: Specifies the `GeoJSON` Point Geometry object. Refer to [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946) for details. ,
Required: True ,
}
object ,
properties:
{
Description: Specifies the parameters to use for the calculation of isochrone polygon. ,
Required: True ,
}
{
departAt:
{
Description: The date and time of departure from the origin point formatted as a dateTime value defined by [RFC 3339, section 5.6](https://www.rfc-editor.org/rfc/rfc3339#section-5.6). When a time zone offset is not specified, UTC will be assumed. If the `departAt` is not set, the default value is the current time. Example: "departAt": "2023-06-01T09:30:00.000-07:00" ,
Format: date-time ,
Required: False ,
}
string ,
isSimplifiedPolygon:
{
Description: Use this to specify whether simplified polygons are required, reducing the number of vertices while preserving the overall shape. Currently, isSimplifiedPolygon only supports true. High-definition polygons are supported in version 2024-07-01-preview ,
Required: False ,
}
boolean ,
optimizeRoute:
{
Description: Specifies the parameter to use to optimize the route. If not defined, the default is "fastestWithoutTraffic" which returns the route to minimize the travel time without using current traffic information. Example: "optimizeRoute":"shortest" ,
Enum:
{
shortest: The route is calculated to minimize the distance. Traffic information is not used. ,
fastestWithoutTraffic: Finds the fastest route, without factoring in traffic information. ,
fastestWithTraffic: The route is calculated to minimize the time using current traffic information. `Note`: Only supported for driving and truck travelMode. ,
}
,
Required: False ,
}
enum ,
avoid:
{
Description: Specifies restrictions that the route calculation should honor when determining the reachable locations. Avoid supports multiple values in a request. Example: "avoid": ["limitedAccessHighways", "tollRoads"] ,
Required: False ,
}
[
string ,
]
,
vehicleSpec:
{
Description: Specifies the vehicle attributes such as vehicle height, weight, max speed, type of cargo, etc. to consider when calculating the reachable locations. This helps avoid low bridge clearances, road restrictions, difficult right turns to provide the optimized truck route based on the vehicle specifications. Vehicle attributes are specified within the vehicleSpec property. ,
Required: False ,
}
object ,
distanceBudgetInMeters:
{
Description: The distance budget specifies the maximum range in meters which can be traveled from the origin waypoint. It cannot be set when `timeBudgetInSec` is specified. The maximum distance supported is 500,000 meters. Example: "distanceBudgetInMeters":5000 ,
Format: float ,
Required: False ,
}
number ,
timeBudgetInSec:
{
Description: The time budget specifies the maximum time in seconds available for travel, defining how far one can go within this time constraint from the origin waypoint. It cannot be set when `distanceBudgetInMeters` is specified. The maximum time supported is 21,600 seconds. Example: "timeBudgetInSec":3600 ,
Format: float ,
Required: False ,
}
number ,
travelMode:
{
Description: Specifies the travel profile to consider when calculating the range polygon. If not specified, the default value is "driving". Example: "travelMode":"driving" ,
Enum:
{
driving: Routing profile suitable for cars are used for range polygon calculation. ,
truck: Routing profile suitable for commercial vehicles like trucks are used for range polygon calculation. ,
}
,
Required: False ,
}
enum ,
}
,
}
,
}

⚐ Response (200)

{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is `FeatureCollection`. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
FeatureCollection: Specifies the `GeoJSON` `FeatureCollection` object type. ,
}
,
Required: False ,
}
enum ,
features:
{
Description: `GeoJSON` feature object that contains Geometry object and additional properties. Refer to [RFC 7946, Section 3.2](https://www.rfc-editor.org/rfc/rfc7946#section-3.2) for details. ,
Required: False ,
}
[
object ,
]
,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for Azure Maps APIs to return error details for failed operations. ,
}
{
error:
{
Description: The error detail. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Required: False ,
}
string ,
message:
{
Description: A human-readable representation of the error. ,
Required: False ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}
Route_PostRouteRangeBatch (new)
Description :  The Route Range Batch API sends batches of up to **100** queries as a single call to the [Route Range API](https://learn.microsoft.com/rest/api/maps/route/post-route-range?view=rest-maps-2025-01-01). >[!Important] >By using this feature, you agree to the preview legal terms. See the [Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional details. ### Submit Synchronous Batch Request The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API. ``` POST https://atlas.microsoft.com/route/range:batch?api-version=2025-01-01 ``` ### POST Body for Batch Request To send the _route range_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 2 _route_range_ queries: ``` { "batchItems": [ { "type": "Feature", "geometry": { "type": "Point", "coordinates": [ 5.86605, 50.9745 ] }, "properties": { "timeBudgetInSec": 6000 } }, { "type": "Feature", "geometry": { "type": "Point", "coordinates": [ -122.201669, 47.615076 ] }, "properties": { "timeBudgetInSec": 2000 } } ] } ``` A _route range_ batchItem object can accept any of the supported _snap to roads_ [Request body](/rest/api/maps/route/post-snap-to-roads?view=rest-maps-2025-01-01#request-body) The batch should contain at least **1** query. ### Batch Response Model The batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types: - [`RouteRangeResponse`](/rest/api/maps/route/post-route-range#response) - If the query completed successfully. - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.
Reference :  Link ¶

⚼ Request

POST:  /route/range:batch
{
x-ms-client-id:
{
Description: Specifies which account is intended for usage in conjunction with the Microsoft Entra ID security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Microsoft Entra ID security in Azure Maps see the following [articles](https://aka.ms/amauthdetails) for guidance. ,
Required: False ,
}
string ,
api-version:
{
Description: Version number of Azure Maps API. ,
Required: True ,
}
string ,
routeRangeBatchRequest:
{
Description: The list of route directions queries/requests to process. The list can contain a max of 100 queries for sync version and must contain at least 1 query. ,
Required: True ,
}
{
batchItems:
{
Description: The list of queries to process. ,
Required: False ,
}
[
object ,
]
,
}
,
}

⚐ Response (200)

{
summary:
{
Description: Summary for the batch request ,
Required: False ,
}
{
successfulRequests:
{
Description: Number of successful requests in the batch ,
Format: int32 ,
Required: False ,
}
integer ,
totalRequests:
{
Description: Total number of requests in the batch ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
batchItems:
{
Description: Array containing the batch results. ,
Required: False ,
}
[
object ,
]
,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for Azure Maps APIs to return error details for failed operations. ,
}
{
error:
{
Description: The error detail. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Required: False ,
}
string ,
message:
{
Description: A human-readable representation of the error. ,
Required: False ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}
Route_PostRouteMatrix (new)
Description :  The `Route Matrix` API is an HTTP `POST` request that allows calculation of a matrix of route summaries for a set of routes defined by origin and destination locations by using a sync request. For every given origin, the service calculates the cost of routing from that origin to every given destination. The set of origins and the set of destinations can be thought of as the column and row headers of a table and each cell in the table contains the costs of routing from the origin to the destination for that cell. Route Matrices can be calculated for driving, walking and truck routes. For example, a food delivery company has 20 drivers and they need to find the closest driver to pick up the delivery from the restaurant. To solve this use case, they can call the Route Matrix API and use the travel cost to sort the drivers by their actual travel distance or time from the restaurant. Route Matrices are used in several different types of applications, most commonly to solve the Traveling Salesman Problem (TSP) and Vehicle Routing Problem (VRP). For each origin-destination pair in the matrix, the travel time and distance are returned. You can use the computed costs to determine which detailed routes to calculate using the Route Directions API. The maximum size of a matrix for sync request it's **2500** (the number of origins multiplied by the number of destinations). ### Submit Synchronous Route Matrix Request If your scenario requires synchronous requests and the maximum size of the matrix is less than or equal to 2500, you might want to make synchronous request. The maximum size of a matrix for this API is **2500** (the number of origins multiplied by the number of destinations). With that constraint in mind, examples of possible matrix dimensions are: 50x50, 60x40, 90x20 (it does not need to be square). ### API Limitations The synchronous processing of matrix is best suited for fast, small matrices of route calculation. To calculate larger matrices and heavy route calculation, use the asynchronous endpoint. The following limitation is applicable to the synchronous requests. If none of the rows in the following table match the request's parameters, the request does not meet the requirements and will not be processed. | Max matrix size | Max number of origins | Max number of destinations | Additional limits |------------------|------------------------|----------------------------|------------| | 100 | 100 | 100 | N/A | | 200 | 200 | 200 | All origins and destinations should be contained in an axis-aligned 400 km x 400 km bounding box. Otherwise, some matrix cells will be resolved as OUT_OF_REGION. | | 2500 | 1000 | 1000 | - `departAt` or `arriveAt` must be any.
- `traffic` must be historical.
- `travelMode` must be either driving or truck
- No other parameters can be used explicitly | Examples: - Request of 10x20 matrix with `traffic=live`: This request will be processed with a bounding box limit, as it matches a limit of up to 200, which includes bounding box restrictions. - Request of 10x20 matrix with default parameters (`traffic=historical`): This request will be processed without a bounding box limit, as it matches a limit of up to 2500, which does not impose bounding box restrictions.
Reference :  Link ¶

⚼ Request

POST:  /route/matrix
{
api-version:
{
Description: Version number of Azure Maps API. ,
Required: True ,
}
string ,
x-ms-client-id:
{
Description: Specifies which account is intended for usage in conjunction with the Microsoft Entra ID security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Microsoft Entra ID security in Azure Maps see the following [articles](https://aka.ms/amauthdetails) for guidance. ,
Required: False ,
}
string ,
routeMatrixRequest:
{
Description: Request body of RouteMatrix API in GeoJSON format. ,
Required: True ,
}
{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is `FeatureCollection`. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
FeatureCollection: Specifies the `GeoJSON` `FeatureCollection` object type. ,
}
,
Required: True ,
}
enum ,
features:
{
Description: A set of origin and destination points passed as GeoJSON MultiPoint features for the input matrix. Refer to [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946) for details on the GeoJSON format. ,
Required: True ,
}
[
{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is Feature. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
Feature: Specifies the `GeoJSON` Feature object type. ,
}
,
Required: True ,
}
enum ,
geometry:
{
Description: A valid `GeoJSON MultiPoint` geometry type. Please refer to [RFC 7946](https://tools.ietf.org/html/rfc7946#section-3.1.3) for details. ,
Required: True ,
}
object ,
properties:
{
Description: MultiPoint feature properties object which specifies the origin features and destination features for the input matrix. ,
Required: True ,
}
{
pointType:
{
Description: Specifies the origin MultiPoint type and destination MultiPoint type for the input matrix. ,
Enum:
{
origins: MultiPoint features that define the origin locations in the input matrix. ,
destinations: MultiPoint features that define the destination locations in the input matrix. ,
}
,
Required: False ,
}
enum ,
}
,
}
,
]
,
departAt:
{
Description: The date and time of departure from the origin point formatted as a `dateTime` value defined by [RFC 3339, section 5.6](https://www.rfc-editor.org/rfc/rfc3339#section-5.6). When a time zone offset is not specified, UTC will be assumed. The `departAt` parameter cannot be used in conjunction with `arriveAt`. The `departAt` also supports: `any` value tailored to the use case where the time context is irrelevant. The `traffic=live` parameter value cannot be used together with `any`. `now` value to set the departure time to the processing time of each individual cell. Processing time may be any time between submission and its completion. This mode is best used together with traffic=live. Default value: `any` if `departAt` is not specified. Example: "departAt": "2024-12-01T09:30:00.000-07:00" ,
Format: date-time ,
Required: False ,
}
string ,
arriveAt:
{
Description: The date and time of arrival at the destination point formatted as a `dateTime` value defined by [RFC 3339, section 5.6](https://www.rfc-editor.org/rfc/rfc3339#section-5.6). When a time zone offset is not specified, UTC will be assumed. The `arriveAt` parameter cannot be used in conjunction with `departAt`. The `arriveAt` also supports `any` value which is tailored to the use case where the time context is irrelevant. The `traffic=live` parameter value cannot be used together with `any`. Default value: `any` if `arriveAt` is not specified. Example: "arriveAt": "2024-12-01T09:30:00.000-07:00" ,
Format: date-time ,
Required: False ,
}
string ,
travelMode:
{
Description: Specifies the travel profile to consider when calculating the matrix. If not specified, the default value is "driving". Example: "travelMode":"driving" ,
Enum:
{
driving: Routing profile suitable for cars are used for route matrix calculation. ,
truck: Routing profile suitable for commercial vehicles like trucks are used for route matrix calculation. ,
walking: The returned routes are optimized for pedestrians, including the use of sidewalks. ,
}
,
Required: False ,
}
enum ,
optimizeRoute:
{
Description: Specifies the parameter to use to optimize the route. If not defined, the default is "fastest" which returns the route to minimize the travel time. Example: "optimizeRoute":"fastest " ,
Enum:
{
fastest: Finds the fastest route to optimize route by travel time. Only `fastest` is supported for the Route Matrix sync API. To use the other types, check the Route Matrix async API. ,
}
,
Required: False ,
}
enum ,
traffic:
{
Description: Specifies how traffic is considered for computing routes. Default value: `historical` ,
Enum:
{
historical: Route calculation considers historical travel times and long term closures. Traffic jams and short-term closures during the travel time window do not influence routing or travel time. ,
live: In addition to historical travel times, route calculation considers traffic jams and short- and long-term closures during the travel time window. `Note`: `traffic=live` may not be used in conjunction with `arriveAt=any` and `departAt=any` ,
}
,
Required: False ,
}
enum ,
avoid:
{
Description: Specifies restrictions that the route calculation should honor when determining the route. Avoid supports multiple values in a request and is only supported for the driving and truck travelMode. ,
Required: False ,
}
[
string ,
]
,
vehicleSpec:
{
Description: Specifies the vehicle attributes such as vehicle height, weight, max speed, type of cargo, etc. to consider when calculating the route matrix. This helps avoid low bridge clearances, road restrictions, difficult right turns to provide the optimized route based on the vehicle specifications. Vehicle attributes are specified within the vehicleSpec property. ,
Required: False ,
}
object ,
}
,
}

⚐ Response (200)

{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is Feature. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
Feature: Specifies the `GeoJSON` Feature object type. ,
}
,
Required: True ,
}
enum ,
geometry:
{
Description: The geometry object is null ,
Required: True ,
}
object ,
properties:
{
Description: Route Matrix properties. ,
Required: True ,
}
{
summary:
{
Description: Summary for the route matrix request ,
Required: False ,
}
{
successfulCount:
{
Description: Number of successful routes within this matrix. ,
Format: int32 ,
Required: False ,
}
integer ,
totalCount:
{
Description: Total number of routes within this matrix. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
matrix:
{
Description: The matrix of route results. ,
Required: False ,
}
[
{
statusCode:
{
Description: The HTTP status code of the current cell. ,
Format: int32 ,
Required: False ,
}
integer ,
originIndex:
{
Description: Index of the origin point ,
Format: int32 ,
Required: False ,
}
integer ,
destinationIndex:
{
Description: Index of the destination point ,
Format: int32 ,
Required: False ,
}
integer ,
departureAt:
{
Description: The estimated departure time, which takes into account the traffic conditions, is formatted as a `dateTime` value defined by [RFC 3339, section 5.6](https://www.rfc-editor.org/rfc/rfc3339#section-5.6). It will reference the timezone offset by either `departAt` or `arrivalAt`. If not, then the UTC time will be used. If departAt or arriveAt is `any`, then departureAt is absent. ,
Format: date-time ,
Required: False ,
}
string ,
arrivalAt:
{
Description: The estimated arrival time, which takes into account the traffic conditions, is formatted as a `dateTime` value defined by [RFC 3339, section 5.6](https://www.rfc-editor.org/rfc/rfc3339#section-5.6). It will reference the timezone offset by either `departAt` or `arrivalAt`. If not, then the UTC time will be used. If departAt or arriveAt is any, then departureAt is absent. ,
Format: date-time ,
Required: False ,
}
string ,
distanceInMeters:
{
Description: Length In Meters property ,
Format: double ,
Required: False ,
}
number ,
durationInSeconds:
{
Description: Estimated travel time in seconds that does not include delays on the route due to traffic conditions. ,
Format: int64 ,
Required: False ,
}
integer ,
durationTrafficInSeconds:
{
Description: The time that it takes, in seconds, to travel a corresponding `TravelDistance` with current traffic conditions. This value is provided if `optimizeRoute` includes traffic considerations. ,
Format: int64 ,
Required: False ,
}
integer ,
error:
{
Description: The error detail. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
message:
{
Description: The error message. ,
Required: False ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: The error details. ,
Required: False ,
}
[
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
message:
{
Description: The error message. ,
Required: False ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: The error details. ,
Required: False ,
}
[
string ,
]
,
additionalInfo:
{
Description: The error additional info. ,
Required: False ,
}
[
{
type:
{
Description: The additional info type. ,
Required: False ,
}
string ,
info:
{
Description: The additional info. ,
Required: False ,
}
object ,
}
,
]
,
}
,
]
,
additionalInfo:
{
Description: The error additional info. ,
Required: False ,
}
[
{
type:
{
Description: The additional info type. ,
Required: False ,
}
string ,
info:
{
Description: The additional info. ,
Required: False ,
}
object ,
}
,
]
,
}
,
}
,
]
,
}
,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for Azure Maps APIs to return error details for failed operations. ,
}
{
error:
{
Description: The error detail. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Required: False ,
}
string ,
message:
{
Description: A human-readable representation of the error. ,
Required: False ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}
Route_PostRouteMatrixAsync (new)
Description :  The `Route Matrix Async` API is an HTTP `POST` request that allows calculation of a matrix of route summaries for a set of routes defined by origin and destination locations by using an asynchronous (async) request. For every given origin, the service calculates the cost of routing from that origin to every given destination. The set of origins and the set of destinations can be thought of as the column and row headers of a table and each cell in the table contains the costs of routing from the origin to the destination for that cell. Route Matrices can be calculated for driving, walking and truck routes. Route Matrices are used in several different types of applications, most commonly to solve the Traveling Salesman Problem (TSP) and Vehicle Routing Problem (VRP). For each origin-destination pair in the matrix, the travel time and distance are returned. You can use the computed costs to determine which detailed routes to calculate using the Route Directions API. The maximum size of a matrix for async request is **50000** (the number of origins multiplied by the number of destinations). ### Submit Asynchronous Route Matrix Request The Asynchronous API is appropriate for processing big volumes of relatively complex routing requests. When you make a request by using async request, by default the service returns a 202 response code along a URL in the `operation-Location` field of the response header with the Azure Maps geography endpoint `{geography}.atlas.microsoft.com. This URL should be checked periodically until the status is Succeeded. The maximum size of a matrix for this API is **50000** (the number of origins multiplied by the number of destinations). With that constraint in mind, examples of possible matrix dimensions are: 500x100, 100x100, 280x170. 100x50 (it does not need to be square). The asynchronous responses are stored for **24** hours. The redirect URL returns a 404 response if used after the expiration period. ``` POST https://atlas.microsoft.com/route/matrix:async?api-version=2025-01-01&subscription-key={subscription-key} ``` Here's a typical sequence of asynchronous operations: 1. Client sends a Route Matrix POST request to Azure Maps 2. The server will respond with one of the following: > HTTP `202 Accepted` - Route Matrix request has been accepted. > HTTP `Error` - There was an error processing your Route Matrix request. This could either be a 400 Bad Request or any other Error status code. 3. If the Matrix Route request was accepted successfully, the `operation-location` header in the response contains the URL to get the status of the request. This status URI looks like the following: ``` GET https://atlas.microsoft.com/route/operations/{id}?api-version=2025-01-01?subscription-key={subscription-key} ``` 4. Client issues a GET request on the resultUrl obtained in Step 3 to get the results ``` GET https://atlas.microsoft.com/route/operations/{id}/result?api-version=2025-01-01?subscription-key={subscription-key} ``` ### API Limitations The asynchronous processing of matrix is best suited for larger matrices that require heavy route calculation. The following limitation is applicable to the asynchronous requests. If none of the rows in the following table match the request's parameters, the request does not meet the requirements and will not be processed. > Async requests supports up to 50K matrix size in a single request. If you want to request an increase to this limit, you can create an Azure Maps Technical Support Request in the Azure portal. | Max matrix size  | Max number of origins | Max number of destinations  | Additional limits | |------------------|-----------------------|-----------------------------|-------------------| | 2500  | 1000  | 1000  | All origins and destinations should be contained in an axis-aligned 400 km x 400 km bounding box. Otherwise some matrix cells will be resolved as OUT_OF_REGION.  | | 50,000  | 10,000  | 10,000  | - `departAt` or `arriveAt` must be any.
- `traffic` must be historical.
- `optimizeRoute` must be fastest.
- `travelMode` must be either driving or truck. 
- No other parameters can be used explicitly.  |
Reference :  Link ¶

⚼ Request

POST:  /route/matrix:async
{
api-version:
{
Description: Version number of Azure Maps API. ,
Required: True ,
}
string ,
x-ms-client-id:
{
Description: Specifies which account is intended for usage in conjunction with the Microsoft Entra ID security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Microsoft Entra ID security in Azure Maps see the following [articles](https://aka.ms/amauthdetails) for guidance. ,
Required: False ,
}
string ,
routeMatrixAsyncRequest:
{
Description: Request body of RouteMatrix API in GeoJSON format. ,
Required: True ,
}
{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is `FeatureCollection`. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
FeatureCollection: Specifies the `GeoJSON` `FeatureCollection` object type. ,
}
,
Required: True ,
}
enum ,
features:
{
Description: A set of origin and destination points passed as GeoJSON MultiPoint features for the input matrix. Refer to [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946) for details on the GeoJSON format. ,
Required: True ,
}
[
{
type:
{
Description: Specifies the `GeoJSON` type. The only supported object type is Feature. For more information, see [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). ,
Enum:
{
Feature: Specifies the `GeoJSON` Feature object type. ,
}
,
Required: True ,
}
enum ,
geometry:
{
Description: A valid `GeoJSON MultiPoint` geometry type. Please refer to [RFC 7946](https://tools.ietf.org/html/rfc7946#section-3.1.3) for details. ,
Required: True ,
}
object ,
properties:
{
Description: MultiPoint feature properties object which specifies the origin features and destination features for the input matrix. ,
Required: True ,
}
{
pointType:
{
Description: Specifies the origin MultiPoint type and destination MultiPoint type for the input matrix. ,
Enum:
{
origins: MultiPoint features that define the origin locations in the input matrix. ,
destinations: MultiPoint features that define the destination locations in the input matrix. ,
}
,
Required: False ,
}
enum ,
}
,
}
,
]
,
departAt:
{
Description: The date and time of departure from the origin point formatted as a `dateTime` value defined by [RFC 3339, section 5.6](https://www.rfc-editor.org/rfc/rfc3339#section-5.6). When a time zone offset is not specified, UTC will be assumed. The `departAt` parameter cannot be used in conjunction with `arriveAt`. The `departAt` also supports: `any` value tailored to the use case where the time context is irrelevant. The `traffic=live` parameter value cannot be used together with `any`. `now` value to set the departure time to the processing time of each individual cell. Processing time may be any time between submission and its completion. This mode is best used together with traffic=live. Default value: `any` if `departAt` is not specified. Example: "departAt": "2024-12-01T09:30:00.000-07:00" ,
Required: False ,
}
string ,
arriveAt:
{
Description: The date and time of arrival at the destination point formatted as a `dateTime` value defined by [RFC 3339, section 5.6](https://www.rfc-editor.org/rfc/rfc3339#section-5.6). When a time zone offset is not specified, UTC will be assumed. The `arriveAt` parameter cannot be used in conjunction with `departAt`. The `arriveAt` also supports `any` value which is tailored to the use case where the time context is irrelevant. The `traffic=live` parameter value cannot be used together with `any`. Default value: `any` if `arriveAt` is not specified. Example: "arriveAt": "2024-12-01T09:30:00.000-07:00" ,
Required: False ,
}
string ,
travelMode:
{
Description: Specifies the travel profile to consider when calculating the matrix. If not specified, the default value is "driving". Example: "travelMode":"driving" ,
Enum:
{
driving: Routing profile suitable for cars are used for route matrix calculation. ,
truck: Routing profile suitable for commercial vehicles like trucks are used for route matrix calculation. ,
walking: The returned routes are optimized for pedestrians, including the use of sidewalks. ,
}
,
Required: False ,
}
enum ,
optimizeRoute:
{
Description: Specifies the parameter to use to optimize the route. If not defined, the default is "fastest" which returns the route to minimize the travel time. Example: "optimizeRoute":"shortest" ,
Enum:
{
shortest: Finds the shortest route to optimize route by travel distance. ,
fastest: Finds the fastest route to optimize route by travel time. ,
}
,
Required: False ,
}
enum ,
traffic:
{
Description: Specifies how traffic is considered for computing routes. Default value: `historical` ,
Enum:
{
historical: Route calculation considers historical travel times and long term closures. Traffic jams and short-term closures during the travel time window do not influence routing or travel time. ,
live: In addition to historical travel times, route calculation considers traffic jams and short- and long-term closures during the travel time window. `Note`: `traffic=live` may not be used in conjunction with `arriveAt=any` and `departAt=any` ,
}
,
Required: False ,
}
enum ,
avoid:
{
Description: Specifies restrictions that the route calculation should honor when determining the route. Avoid supports multiple values in a request and is only supported for the driving and truck travelMode. ,
Required: False ,
}
[
string ,
]
,
vehicleSpec:
{
Description: Specifies the vehicle attributes such as vehicle height, weight, max speed, type of cargo, etc. to consider when calculating the route matrix. This helps avoid low bridge clearances, road restrictions, difficult right turns to provide the optimized route based on the vehicle specifications. Vehicle attributes are specified within the vehicleSpec property. ,
Required: False ,
}
object ,
}
,
}

⚐ Response (202)

{
operation-location:
{
Description: URL to check the status of the asynchronous operation. ,
}
string ,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for Azure Maps APIs to return error details for failed operations. ,
}
{
error:
{
Description: The error detail. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Required: False ,
}
string ,
message:
{
Description: A human-readable representation of the error. ,
Required: False ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}
Route_GetRouteOperationsStatus (new)
Description :  Get the status of an asynchronous operation by its operation ID.
Reference :  Link ¶

⚼ Request

GET:  /route/operations/{id}
{
api-version:
{
Description: Version number of Azure Maps API. ,
Required: True ,
}
string ,
id:
{
Description: System generated unique identifier for the asynchronous operation after it has been submitted. ,
Required: True ,
}
string ,
}

⚐ Response (200)

{
id:
{
Description: Unique identifier for the asynchronous operation. ,
Required: False ,
}
string ,
status:
{
Description: Current status of the async operation. ,
Enum:
{
NotStarted: The operation has not started yet. ,
Running: The operation is running. ,
Completed: The operation has completed successfully. ,
Failed: The operation has failed. ,
}
,
Required: False ,
}
enum ,
kind:
{
Description: Type of asynchronous operation ,
Enum:
{
RouteMatrix: Route matrix asynchronous job. ,
}
,
Required: False ,
}
enum ,
result:
{
Description: The result of async operation ,
Required: False ,
}
{
resultUrl:
{
Description: URL to the get the result of async operation ,
Format: uri ,
Required: False ,
}
string ,
}
,
createdAt:
{
Description: Timestamp when the operation was created. ,
Format: date-time ,
Required: False ,
}
string ,
lastActionAt:
{
Description: Timestamp when the operation status was updated. ,
Format: date-time ,
Required: False ,
}
string ,
error:
{
Description: The error detail. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
message:
{
Description: The error message. ,
Required: False ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: The error details. ,
Required: False ,
}
[
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
message:
{
Description: The error message. ,
Required: False ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: The error details. ,
Required: False ,
}
[
string ,
]
,
additionalInfo:
{
Description: The error additional info. ,
Required: False ,
}
[
{
type:
{
Description: The additional info type. ,
Required: False ,
}
string ,
info:
{
Description: The additional info. ,
Required: False ,
}
object ,
}
,
]
,
}
,
]
,
additionalInfo:
{
Description: The error additional info. ,
Required: False ,
}
[
{
type:
{
Description: The additional info type. ,
Required: False ,
}
string ,
info:
{
Description: The additional info. ,
Required: False ,
}
object ,
}
,
]
,
}
,
}

⚐ Response (404)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.). ,
}
{
error:
{
Description: The error object. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
message:
{
Description: The error message. ,
Required: False ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: The error details. ,
Required: False ,
}
[
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
message:
{
Description: The error message. ,
Required: False ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: The error details. ,
Required: False ,
}
[
string ,
]
,
additionalInfo:
{
Description: The error additional info. ,
Required: False ,
}
[
{
type:
{
Description: The additional info type. ,
Required: False ,
}
string ,
info:
{
Description: The additional info. ,
Required: False ,
}
object ,
}
,
]
,
}
,
]
,
additionalInfo:
{
Description: The error additional info. ,
Required: False ,
}
[
{
type:
{
Description: The additional info type. ,
Required: False ,
}
string ,
info:
{
Description: The additional info. ,
Required: False ,
}
object ,
}
,
]
,
}
,
}
,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.). ,
}
{
error:
{
Description: The error object. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
message:
{
Description: The error message. ,
Required: False ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: The error details. ,
Required: False ,
}
[
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
message:
{
Description: The error message. ,
Required: False ,
}
string ,
target:
{
Description: The error target. ,
Required: False ,
}
string ,
details:
{
Description: The error details. ,
Required: False ,
}
[
string ,
]
,
additionalInfo:
{
Description: The error additional info. ,
Required: False ,
}
[
{
type:
{
Description: The additional info type. ,
Required: False ,
}
string ,
info:
{
Description: The additional info. ,
Required: False ,
}
object ,
}
,
]
,
}
,
]
,
additionalInfo:
{
Description: The error additional info. ,
Required: False ,
}
[
{
type:
{
Description: The additional info type. ,
Required: False ,
}
string ,
info:
{
Description: The additional info. ,
Required: False ,
}
object ,
}
,
]
,
}
,
}
,
}
Route_GetRouteOperationsResult (new)
Description :  Get the result of an asynchronous operation by its operation ID.
Reference :  Link ¶

⚼ Request

GET:  /route/operations/{id}/result
{
api-version:
{
Description: Version number of Azure Maps API. ,
Required: True ,
}
string ,
x-ms-client-id:
{
Description: Specifies which account is intended for usage in conjunction with the Microsoft Entra ID security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Microsoft Entra ID security in Azure Maps see the following [articles](https://aka.ms/amauthdetails) for guidance. ,
Required: False ,
}
string ,
Accept-Language:
{
Description: Language in which routing results should be returned. For more information, see [Localization support in Azure Maps](https://learn.microsoft.com/azure/azure-maps/supported-languages#routing-v2-services-preview-supported-languages). ,
Required: False ,
}
string ,
id:
{
Description: System generated unique identifier for the asynchronous operation after it has been submitted. ,
Required: True ,
}
string ,
}

⚐ Response (200)

{
kind:
{
Description: Type of asynchronous operation ,
Enum:
{
RouteMatrix: Route matrix asynchronous job. ,
}
,
Required: True ,
}
enum ,
}

⚐ Response (404)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for Azure Maps APIs to return error details for failed operations. ,
}
{
error:
{
Description: The error detail. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Required: False ,
}
string ,
message:
{
Description: A human-readable representation of the error. ,
Required: False ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: Error code of the error that occurred. ,
}
string ,
}
,
$schema:
{
Description: Common error response for Azure Maps APIs to return error details for failed operations. ,
}
{
error:
{
Description: The error detail. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Required: False ,
}
string ,
message:
{
Description: A human-readable representation of the error. ,
Required: False ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: The error code. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}